Magic-API管理系统使用说明

系统版本：1.2.1 (20240105)

文档创建日期：2023/11/28

文档最后更新：2024/01/05

一、系统部署

基础软件部署

• 此步骤Linux和Windows通用；

1. 安装配置Mysql 5.7或更新版本(安装配置过程不在此详述);

   • 配置Mysql参数，解决同步大数据接口时报错的问题:

     1
     [mysqld]
     2
     max_allowed_packet = 100M
     

   • 初始化数据，客户端工具连接Mysql:

     在Mysql系统中，创建数据库:

     属性	值
     Database Name	magic
     Character set	utf8mb4
     Collation	utf8mb4_general_ci

     打开magic数据库，在查询窗口中执行initMagicApi.sql脚本，初始化数据;

2. 安装配置Redis 6.2.x或更新版本(安装配置过程不在此详述);

3. 安装配置JDK 1.8.0_291或更新版本(安装配置过程不在此详述);

   • 启用256位以上的密码策略强度:

     xxxxxxxxxx
     2
     1
     cd $JRE_TOP/lib/security
     2
     vi java.security
     

     将#crypto.policy=unlimited前面的 # 号去掉,变成:

     xxxxxxxxxx
     1
     1
     crypto.policy=unlimited
     

部署步骤(Linux)

• 部署Magic-API管理系统，本次部署以路径/usr/local/为例说明，实际部署时根据项目情况修改;

1. 创建目录:

   xxxxxxxxxx
   10
   1
   cd /usr/local
   2
   mkdir magic-api
   3
   mkdir -p magic-api/data
   4
   mkdir -p magic-api/images
   5
   mkdir -p magic-api/logs/info
   6
   mkdir -p magic-api/logs/debug
   7
   mkdir -p magic-api/logs/warn
   8
   mkdir -p magic-api/logs/error
   9
   mkdir -p magic-api/logs/plumelog
   10
   mkdir -p magic-api/uploadpath
   

2. 上传下列文件至/usr/local/magic-api目录下:

   序号	文件名	类型	说明
   1	madmin.sh	shell脚本	启动/停止Magic-API的Linux脚本
   2	application.yml application-prod.yml application-shiro.yml application-static.yml logback-spring.xml magic-editor-config.js	配置文件	程序运行的配置项信息
   3	license.lic publicCerts.keystore	许可证书	授权管理的许可证书文件
   4	magic-api.jar	jar文件	程序文件
   5	initMagicApi.sql	sql文件	初始化系统的sql语句
   6	images目录下的 loginbackground.jpeg loginlogo.png background.jpeg	图片	可根据需要替换图片 loginbackground.jpeg:系统登录首页背景图片 loginlogo.png:系统登录首页logo图片 background.jpeg:系统主界面首页背景图片

3. 修改配置信息

   • 配置文件信息请参见“系统配置文件”部分说明;

4. 修改文件可执行权限:

   xxxxxxxxxx
   3
   1
   cd /usr/local/magic-api
   2
   chmod +x magic-api.jar
   3
   chmod +x madmin.sh
   

5. 启动系统:

   • 启动Magic-API管理系统:

     xxxxxxxxxx
     2
     1
     cd /usr/local/magic-api
     2
     ./madmin.sh start
     

   • 停止Magic-API管理系统:

     xxxxxxxxxx
     2
     1
     cd /usr/local/magic-api
     2
     ./madmin.sh stop
     

部署步骤(Windows)

• 部署Magic-API管理系统，本次部署以路径c:\software\为例说明，实际部署时根据项目情况修改;

1. 创建目录:

   xxxxxxxxxx
   10
   1
   cd c:\software\
   2
   mkdir magic-api
   3
   mkdir magic-api\data
   4
   mkdir magic-api\images
   5
   mkdir magic-api\logs\info
   6
   mkdir magic-api\logs\debug
   7
   mkdir magic-api\logs\warn
   8
   mkdir magic-api\logs\error
   9
   mkdir magic-api\logs\plumelog
   10
   mkdir magic-api\uploadpath
   

2. 上传下列文件至c:\software\magic-api\目录下:

   序号	文件名	类型	说明
   1	admagicstart.bat	bat脚本	启动/停止Magic-API的Windows脚本
   2	application.yml application-prod.yml application-shiro.yml application-static.yml logback-spring.xml magic-editor-config.js	配置文件	程序运行的配置项信息
   3	license.lic publicCerts.keystore	许可证书	授权管理的许可证书文件
   4	magic-api.jar	jar文件	程序文件
   5	initMagicApi.sql	sql文件	初始化系统的sql语句
   6	images目录下的 loginbackground.jpeg loginlogo.png background.jpeg	图片文件	可根据需要替换图片 loginbackground.jpeg:系统登录首页背景图片 loginlogo.png:系统登录首页logo图片 background.jpeg:系统主界面首页背景图片

3. 修改配置信息

   配置文件信息请参见“三、系统配置文件”部分说明;

4. 修改文件可执行权限:

   确保执行命令的用户对magic-api.jar有读取和执行的权限。

5. 启动系统:

   • 启动Magic-API管理系统:

     xxxxxxxxxx
     2
     1
     cd c:\software\magic-api
     2
     admagicstart.bat
     

   • 停止Magic-API管理系统:

     关闭命令行窗口即可；

二、系统登录

登录地址

• 在浏览器中输入地址访问系统(根据实际IP地址和端口修改):

http://127.0.0.1:8888/index

用户名/密码

用户名: admin密 码：admin123

注意事项

1. 请使用Chrome/Firefox/Edge浏览器访问，部分功能页面不支持IE系列；

2. 为保证正常访问系统，请在服务器端放行防火墙对端口的访问权限；

3. 如果Redis服务器和Magic-API服务器不在同一台机器上，请在服务器端放行防火墙对Redis服务器端口的访问权限；

三、系统配置文件

sh/bat脚本文件

对于Linux系统，修改madmin.sh，用记事本编辑脚本文件，将其中的JAVA_TOP路径修改为实际jre/jdk安装的路径:

​x
1
#!/bin/bash
2
3
# 取得当前Shell脚本所在绝对路径
4
MAGIC_API=$(cd "$(dirname "$0")";pwd)
5
JAVA_TOP=$MAGIC_API/jdk1.8.0_291
6
......

对于Windows系统，修改admagicstart.bat，用记事本编辑脚本文件，将其中的JAVA_TOP路径修改为实际jre/jdk安装的路径:

xxxxxxxxxx
13
1
@echo off
2
:设置窗口字体颜色
3
color 0a
4
mode con cols=60 lines=12
5
:设置窗口标题
6
TITLE magic-api管理程序(windows版)
7
8
set MAGIC_FILE=magic-api.jar
9
set MAGIC_LOG=magic-api.log
10
set JAVA_TOP=C:\Program Files\Java\jdk1.8.0_144
11
set JAR_PARAS=-Dfile.encoding=utf-8 -Djava.net.preferIPv4Stack=true
12
set MAGIC_TOP=%~dp0
13
......

yml配置文件

1. 建议只修改application-prod.yml文件，其它yml文件保持默认配置；

2. 配置测试环境时，可将application-prod.yml命名为application-dev.yml，同时修改application.yml中active: prod为active: dev即可；

3. 注意Linux系统路径使用/正斜杠，Windows系统路径使用\反斜杠；

• 项目相关配置

xxxxxxxxxx
8
1
# 项目相关配置
2
cfg-project:
3
  name: Magic-API管理系统  # 程序名称，可根据项目需要修改
4
  version: 4.7.7   # 系统框架版本，默认即可
5
  copyrightYear: 2023   # 版权年份   
6
  # 文件路径(用于上传用户头像,Windows配置D:/magic/uploadPath，Linux配置 /home/magic/uploadPath)
7
  # 需要修改为项目实际路径
8
  profile: /usr/local/magic-api/uploadpath

• 环境配置

xxxxxxxxxx
3
1
# 环境配置
2
cfg-server:
3
  port: 8888   # 应用程序运行的HTTP端口(默认为80)

• Magic-API配置信息

xxxxxxxxxx
13
1
# Magic-API配置信息
2
cfg-magic-api:
3
  backup-max-history: 180    # Magic-API备份保留天数，-1为永久保留
4
  # 前端界面引用的js文件，需要修改为项目实际路径
5
  editor-config: /usr/local/magic-api/magic-editor-config.js
6
  # Magic接口放行地址，不受ruoyi框架控制
7
  exclude-path-patterns: /root/**,/erp/**,/test/**
8
  # Magic禁止通过import env查看的配置信息
9
  excludeEnvKey: '*.password,*.storePwd,*.secret-key'
10
  # 实例ID，集群环境下，要保证每台机器不同。默认启动后随机生成uuid，如无特殊情况可不配置。
11
  instanceId: 20927d75-7fa0-237d-80ed-c3b5b6f1a498
12
  # 远程推送时的秘钥，未配置则不开启推送
13
  secret-key: 

• 数据源配置

xxxxxxxxxx
6
1
# 数据源配置，需要修改为数据库的实际配置信息
2
cfg-datasource:
3
  driverClassName: com.mysql.cj.jdbc.Driver
4
  url: jdbc:mysql://127.0.0.1:3306/magic?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8
5
  username: root
6
  password: root

• Redis配置

xxxxxxxxxx
6
1
# 配置redis数据源
2
cfg-redis:
3
  database: 0
4
  host: 127.0.0.1
5
  port: 6379
6
  password: test123

• 登录配置

xxxxxxxxxx
5
1
# 登录配置
2
cfg-login:
3
  captchaEnabled: true    # 登录界面是否启用验证码
4
  expireTime: 60     # Session超时时间，-1代表永不过期（默认30分钟）
5
  maxRetryCount: 5   # 密码错误连续超过{maxRetryCount}次锁定10分钟

• Swagger配置

xxxxxxxxxx
3
1
# Swagger配置，注意正式环境需要关闭，设置为false；测试环境可打开，设置为true；
2
cfg-swagger:
3
  enabled: false     # 是否开启swagger

• logging配置

xxxxxxxxxx
5
1
# logging配置
2
cfg-log:
3
  # config配置文件，需要修改为项目的实际路径
4
  configfile: /usr/local/magic-api/logback-spring.xml
5
  path: /usr/local/magic-api/logs

• Jasypt加密配置

xxxxxxxxxx
3
1
# jasypt加密，如果不清楚含义，可保持默认
2
cfg-jasypt:
3
  password: 02700083-9fd9-4b82-a4b4-9177e0560e92

• License证书管理配置

xxxxxxxxxx
7
1
# license证书管理，需要修改证书主题subject，以及证书路径为项目实际路径
2
cfg-license:
3
  subject: MagicAPI管理系统
4
  public-pwd: magic666
5
  storePwd: magic666
6
  public-keys-store-path: /usr/local/magic-api/publicCerts.keystore
7
  license-path: /usr/local/magic-api/license.lic

js配置文件

magic-editor-config.js，前端运行需要配置信息，一般修改baseURL、serverURL、title三个信息即可；

xxxxxxxxxx
12
1
var MAGIC_EDITOR_CONFIG = {
2
    baseURL: 'http://localhost:8888/magic/web', //需要修改为实际的端口
3
    serverURL: 'http://localhost:8888/',    // 需要修改为实际的端口
4
    title: 'Magic-API管理',   // 可根据需要修改为项目的名称
5
    checkUpdate: false,
6
    autoSave: true,
7
    decorationTimeout: 10000,
8
    document: false,
9
    jdbcDrivers: ['com.mysql.cj.jdbc.Driver','oracle.jdbc.driver.OracleDriver','org.postgresql.Driver','com.microsoft.sqlserver.jdbc.SQLServerDriver','dm.jdbc.driver.DmDriver','org.apache.hive.jdbc.HiveDriver','com.taosdata.jdbc.rs.RestfulDriver'],
10
    datasourceTypes: ['com.zaxxer.hikari.HikariDataSource', 'com.alibaba.druid.pool.DruidDataSource','org.apache.tomcat.jdbc.pool.DataSource','org.apache.commons.dbcp2.BasicDataSource']
11
    // 其它配置参考本页中其它配置项
12
}

四、系统说明

本系统是在原开源magic-api接口快速开发框架的基础上，保留其强大、易用的特性，针对企业权限管控需求及实际项目需要，增加系统用户管理、角色管理、菜单管理、安全性管理、日志管理等功能，整合形成Magic-API接口管理系统。

magic-api接口快速开发框架的特点：

基于Java的接口快速开发框架，编写接口将通过magic-api提供的UI界面完成，自动映射为HTTP接口，无需定义Controller、Service、Dao、Mapper、XML、VO等Java对象即可完成常见的HTTP API接口开发

magic-api官网快速入门、基础教程链接：

https://www.ssssssss.org/magic-api/pages/quick/intro/

接口访问权限控制-前端界面

本系统通过“用户<->角色<->菜单<->接口”实现用户接口权限管控；用户通过前端UI界面在magic-api平台创建的分组、接口，由系统自动同步到菜单项目中；角色授权时通过勾选对应接口，再分配角色至用户，即可实现对用户前端界面操作接口的权限控制：

• 一个用户可分配多个角色，权限取各角色权限的并集；

用户自己在magic-api创建成功的分组、接口，无需由管理员额外授权，可由本人即时获得对该分组/接口查看/编辑管理的权限；

分配了“[内置]Magic接口同目录查看”角色的用户，如果拥有某个目录的访问权限，则自动获得其他用户在此目录下创建的接口查看权限（注意不能自动获得此目录下子目录的查看权限）；

接口访问权限控制-第三方调用

此模式基于Oauth2.0的客户端凭据机制；这种场景下的授权，便是客户端凭据许可，第三方软件可以直接使用注册时的 client_id 和 client_secret 来换回访问令牌 token 的值。其原理如下：

本系统通过“Client<->角色<->菜单<->接口”实现Client ID接口权限控制；在角色定义界面绑定角色与菜单项目(即接口)的关系 ，再分配角色至指定的Client ID，即可实现对Client ID访问接口的权限控制：

• 和一个用户可分配多个角色不同，一个Client ID只允许分配一个角色，且Client ID账户无法登录前端系统；

客户端凭据访问接口步骤：

1. 获取动态token(以账号dms-client为例):

   Key	value
   client_id	dms-client
   client_secret	668f73c4-ec2e-8745-0c91-1194133e958b
   grant_type	client_credentials

   接口访问信息：

   参数名	参数值
   接口地址	http://127.0.0.1:8888/oauth2/client_token
   调用方式	POST
   调用参数	client_id:dms-client client_secret:668f73c4-ec2e-8745-0c91-1194133e958b grant_type:client_credentials
   encType	application/x-www-form-urlencoded

   调用接口成功后，返回结果data.client_token值即为获得的动态token；

2. 调用接口:

   调用接口时，在Headers中添加access_token参数(POST和GET方式相同)，这里的参数值即为上一步获得的动态token:

   参数名	参数值
   access_token	mPx6cs5SVPwLznivShOfhSNvjMqcjRYmhDq4irxqKejxW3JNHrwSYNDcEDnl

匿名模式&静态token

• 匿名模式

  对于处在企业内部网络的系统接口调用，采用客户端凭据获取动态token方式比较麻烦，系统提供简化的接口访问方式，跳过身份认证这个步骤:

针对单个接口，在接口配置选项处设置允许匿名访问(anonymous=true)：

• 静态token

  相对于匿名模式，需要调用方提供一个固定值的token访问接口；配置步骤:

  1. 设置全局静态token(路径：系统管理->参数设置，参数键名：sys.magic.statictoken，参数名称：magic:接口是否启用静态token)：

      

  2. 在接口选项处，设置两个选项(enabled_static_token和anonymous为true)：

  3. 调用接口时，在接口url或header处传入参数token=xxxxxxxxxx(第1步设置的全局静态token值)：

      

接口日志查询

• 通过前端界面，对接口的新增、修改、删除等操作，可通过[接口管理->接口日志->接口操作]查询：

   

• 通过接口调用(magic-api管理界面在线调试，或第三方系统调用)，对接口的调度操作，可通过[接口管理->接口日志->接口调度]查询：

定时任务

本系统提供定时任务管理，可实现对接口的调度运行，[系统监控->定时任务]:

配置定时任务调用Magic-API接口时，调用目标字符串各参数的含义：

参数项	参数说明	说明
Bean调用名称	magicTask.run	固定值
第一个参数	接口调用方式	接口的调用方式，get/post
第二个参数	接口相对路径	这里填写接口的相对路径，如interface/test/queryInfo； 相对路径的获取方式：在Magic-API接口管理界面，鼠标选择接口，右键->复制相对路径
第三个参数	接口参数	要传入接口的参数； POST调用 ：{body:map}，body为固定变量名，map为接口要处理的实际Json参数； GET调用：{paraname1:paravalue1, paraname2:paravalue2,…}
第四个参数	接口日志记录	是否在[接口管理->接口日志->接口调度]记录接口调度日志信息； true:记录接口调度日志； false:不记录接口调度日志; 注意：不管参数如何设置，在定时任务管理界面的日志按钮查看页面，都可查看接口的调度日志信息；

执行策略详解：

立即执行：（所有misfire的任务会马上执行）打个比方，如果9，10点的任务都misfire了，在10：15系统恢复之后，9点，10点的misfire会马上执行执行一次：（会合并部分的misfire，正常执行下一个周期的任务）假设9，10点的任务都misfire了，系统在10：15分起来了。只会执行一次misfire，下次正点执行。放弃执行：(所有的misfire不管，执行下一个周期的任务)

接口选项说明

系统中内置了接口选项，以下是对各选项作用的说明:

参数设置说明

系统内置了参数设置，以下是对各主要参数作用的说明:

配置文件敏感数据加密

在定义配置文件application-prod.yml时，涉及到数据库连接密码或远程推送时秘钥等敏感数据：

可以通过加密的方式防止这些敏感数据泄露，具体操作步骤：

1. 确定加密密钥，这里示例如：Magic123，记住这个密钥，后面在生成加密密文以及启用系统时需要；

2. 菜单：系统工具->加密解密，打开加密解密页面：

    

3. 在Jasypt加密处，密钥处输入第1步确定的加密密钥的Magic123，明文输入root，这个root是配置文件中cfg-datasource.password的密码明文，点击“加密”按钮，生成密文wUO0iddnIn49HTYhbprxLg==；

   注意：相同密钥和明文，生成的密文不是唯一的，每点击一次加密，生成的密文都会变化，这里取任意一次生成的密文都可以。

4. 将生成的密文用如下格式替换原来的root密码：ENC(密文)

    

5. 保存配置文件，用./madmin.sh stop退出系统；用如下命令启动系统：

   xxxxxxxxxx
   1
   1
   ./madmin.sh runsecure
   

    

6. 系统提示输入密码：

    

7. 这里输入第1步确定的加密密钥Magic123，该密钥也是对密码加密后密文的解密密钥。确认系统启动：

    

数据源扩展

magic-api接口平台支持多数据源，包括但不限于（只要符合jdbc规范的都可以）以下数据库，如：

MySQL、MariaDB、Oracle、DB2、PostgreSQL、SQLServer、MongoDB

其它如国产的达梦数据库、涛思数据库等也支持；

本系统内置了MySQL、Oracle、PostgreSQL、SQLServer、MongoDB数据库的驱动，开箱即用。其它数据库需要根据不同版本集成对应jdbc驱动文件才可使用。

存储过程调用

本系统对magic-api做了扩展，可支持基础数据类型参数的存储过程调用：

XML报文支持

本系统对接口调用做了扩展，支持调用时XML报文参数；注意这不是基于XML的WebService服务，只是支持XML数据的HTTP调用；

• 要启用接口对XML报文作为传入参数的支持，在接口配置选项处指定xml_param_in=true：

传入XML参数时，前端界面无法直接调试，可通过PostMAN等工具进行测试；

• 要启用接口对XML报文作为传出结果的支持，在接口配置选项处指定xml_resp_out=true：

  设置前的输出结果：

  设置后的输出结果：